RighTime v1.0a, TestTime v1.0a Copyright 1991, GTBecker March 30, 1991 All rights reserved Shareware Notice This file (RIGHTIME.TXT) and evaluation program files RIGHTIME.COM and TESTTIME.COM should be contained in the shareware distribution file. Neither evaluation program will run if RIGHTIME.TXT is missing from the same directory or has been modified in any way. These files are the copyrighted property of G.T. Becker and Air System Technologies, Inc. of Dallas, Texas, USA. You may use these evaluation programs for up to one month, and you may - and are encouraged to - pass the shareware distribution file along to others, but you may not modify, rename or sell the files or programs to anyone under any circumstances. Shareware distributors may charge a reasonable fee for their services and media. You are encouraged to register your usage of RighTime. Registered RighTime users receive a diskette containing the current version of the registered programs, a printed user manual and usage license, notification of new releases, and enthusiastic support from the author when you need it. The registered version of RighTime is functionally identical to this shareware distributed version, but it lacks registration reminders, the requirement that all files remain resident, and it is serial numbered. Beyond the immediate tangible benefits, registration also provides support for the shareware software distribution concept. Shareware means quality software that you try before you buy. More happy shareware users means more happy shareware authors that produce more shareware distributed program offerings. We all benefit, but only if the users do their ultimate part of registering. If RighTime is a useful addition to your system, please register your usage. To register, fill in the form at the end of this document and send it and US$25 for a single machine to Air System Technologies, 14232 Marsh Lane, Suite 339, Dallas, Texas, 75234, USA. Site licensing is available. What is RighTime? RIGHTIME.COM is a TSR for MSDOS v3.0 and later which will correct PC/AT "CMOS"-type clock error up to about 5.5 minutes per day; if RighTime is automatically and dependably installed via AUTOEXEC.BAT as suggested below, the system clock will behave as properly and accurately as one should hope the system clock of a computer would. Written in 80286 assembly language, the resident portion occupies only 3K of system memory. First, here is what RighTime cannot do: - RighTime cannot correct clock boards or computer motherboard clocks that do not emulate the PC/AT hardware clock and its BIOS support precisely; AT&T PC 6300, AST Six Pack boards and the like are not supported. - RighTime cannot properly correct an unstable clock; most clocks are slow or fast and they are essentially unvarying. If your clock wanders aimlessly, repair the hardware first. RighTime exploits the better qualities of each of the two clocks in your system and improves upon them by doing three fundamental things: * RighTime slaves the DOS system clock (which has higher resolution) to the hardware clock (which has higher stability), * RighTime improves and maintains accuracy by regularly calculating and applying corrections to both clocks, and * RighTime monitors time set commands (and the equivalent system calls from any program) to learn the hardware clock error rate. RighTime intrinsically sets the hardware clock and solves the midnight rollover date bug that exists in some DOS versions; this eliminates the need for other utility programs or drivers that perform these functions. The hardware clock seconds transition will also be properly set by RighTime. Each time you set the time, RighTime will improve the accuracy of the corrections and will subsequently improve the accuracy of the clocks. It should be easy to achieve a worst-case error of less than 0.5 second per day and under good conditions, less than 0.5 second per week; typical results are ten times better. Large time changes (larger than approximately 5.5 minutes) will not affect the corrections, permitting standard time to daylight time and the converse adjustments. Some rogue programs apparently change the 8254 timer load constant resulting in a suddenly fast clock which requires a reboot to correct; reexecuting RighTime will load the right value (which will restore the proper rate) and indicate the correct time without resetting the time if it is done reasonably promptly. Getting Started To use RighTime, first decide where to store the corrections. There are three options: unused CMOS RAM, disk file, or neither. If you have only floppies the disk file option is impractical, so try the CMOS RAM option. If you have a hard disk, you can probably use either the CMOS RAM or the disk file option. The CMOS RAM option involves some initial bravado: not all BIOS ROMs use CMOS RAM similarly, so before attempting to use the CMOS RAM option, be forewarned that CMOS RAM contains system setup data that RighTime might inadvertently disturb; be prepared to reset the setup data if the CMOS RAM option is unsuccessful on your system. See the Hardware Compatibility List, below. If this dissuades you or if you are otherwise reluctant, use the disk file option until you gain some confidence. If you chose the disk file option, RighTime will attempt to write to its own program file from time to time, so write access must be allowed. RighTime can also be configured with no correction storage, with consequential loss of some of its utility (see No Correction Storage Option, below). If you know how fast or slow your clock appears to run per day, you can optionally speed the learning process of RighTime by suggesting a correction to the program as a signed number in hundredths of a second, positive for a slow clock, negative for a fast clock. For example, if your clock runs about two minutes fast per day, the suggested correction should be -12000 (120 seconds times 100). There are actually two corrections that RighTime normally applies, one while the system is running and warm, and another when the system is turned off and cool. If you know the cool correction, suggest it also. If you don't know one or you know neither correction, RighTime will determine them anyway; it'll just take longer for the corrections to mature to good accuracy. If you have been using another resident driver or TSR to correct the weaknesses of your clock, remove all references to it from your CONFIG.SYS and AUTOEXEC.BAT files and, once you are confident that RighTime is all it purports to be, remove the other driver or TSR from your system. To get started, place RIGHTIME.COM in some directory (dev:\path, which does not need to be included in a PATH statement), and run it from the DOS prompt: if you chose the CMOS RAM option, dev:\path\RighTime /R /Wwarm /Ccool or dev:\path\RighTime /R /W /C if you chose the disk file option, dev:\path\RighTime /F /Wwarm /Ccool or dev:\path\RighTime /F /W /C Also, in your AUTOEXEC.BAT file (as the first TSR, but after any PROMPT, PATH or SET statements), add: if you chose the CMOS RAM option, dev:\path\RighTime /R if you chose the disk file option, dev:\path\RighTime /F For example, I put RIGHTIME.COM in C:\DOS\TIME, my clock runs about 1.5 seconds fast per day when warm, and I use the CMOS RAM option. I started by running C:\DOS\TIME\RighTime /R /W-150 /C and I added this line to my AUTOEXEC.BAT file: C:\DOS\TIME\RighTime /R Had I chosen the disk file option, I would have run C:\DOS\TIME\RighTime /F /W-150 /C and I would have added this line to my AUTOEXEC.BAT: C:\DOS\TIME\RighTime /F If RighTime encounters difficulty during its installation, it will report one of several messages and terminate (see Installation Error Messages, below). A successful installation will display the corrections, an "Installed" message and a copyright notice. Setting the Time Now that RighTime is installed and running, set the date and time as accurately as possible. If you have access to a time standard, use it. For best accuracy, use a NIST telephone service time setting program such as Professional TimeSet v6.0 by Peter Petrakis. Alternatively, you can listen to WWV or CHU or a radio network news broadcast and be prepared to set your clock when you hear the beep on the minute or hour. Don't use a radio station that is airing a call-in talk show; the audio is usually delayed six to ten seconds on such programs to allow for profanity dumping, and so the beep will be equally late. An all-news format station is probably not delayed. To be certain, call the radio station and ask for engineering; they will know. Local telephone time services are usually poor; don't trust that they are correct. What is important is accuracy; RighTime needs a reference to initially learn from, and unless you care to (and know how to) automate it, you are it. From this moment on, RighTime will monitor each time set occurrence, learning from your adjustments. Whenever you notice or suspect that the indicated DOS system time is insufficiently correct to satisfy you, reset it accurately. Separate time sets by a minimum of 30 minutes. You will find that the clocks will become more and more accurate and the need for adjustment will decrease, becoming infrequent; you must, however, set the time accurately at least once per month. When you turn your computer on, allow it to boot and then, if it is necessary, set the time accurately within ten minutes of boot. Time adjustments that are performed within ten minutes of boot will affect the cool correction; adjustments performed after that ten minute period will affect the warm correction. Each time you reboot, RighTime will display the current corrections. After a few days of your occasional diligent time setting, the corrections should settle to fairly constant numbers, which will be true indications of the uncorrected performance of your hardware clock. Once it is installed, you can also display the current corrections by simply running RighTime again at a DOS prompt (no parameters are required). The correction that is currently being applied to the DOS clock will be displayed and a functional self test will also be performed, verifying that RighTime is currently running properly on your system. As long as RighTime is in use and you've been diligent in your adjustments, and the corrections have matured, the hardware clock error will not be more than 0.5 second, and the DOS clock will be much more accurate than that. In fact, the DOS clock error can be less than 0.01 second; but since DOS can't express the time any better than the 55 millisecond tick rate permits, this accuracy might not be easily seen. Nevertheless, it is there. A tool is provided with RighTime that allows verification and visualization of RighTime's actions; see TestTime, below. RighTime has limits of one week of inactivity, and one month between time sets, that can be corrected to a maximum of 5 minutes, 27.67 seconds per occasion; beyond that, all bets are off. In that case, unpredictable, and probably incorrect, clock changes can occur, but if it can, RighTime will advise you of its difficulty. For example, if your clock runs two minutes slow per day and you don't use the system for three full days, when you boot up you will receive a message warning that the clock needs to be adjusted manually. The subsequent adjustment will not affect the corrections. Similarly, if you only set the time twice each year, RighTime is not for you and will not cope well. No Correction Storage Option If you have difficulty with both the CMOS RAM and disk file options or you need or wish to use neither option, RighTime can still correct the clocks for as long as the system runs continuously. What RighTime has learned will be lost when you reboot or power down, and there can be no cool correction. Otherwise, all of the comments above apply. If you suggest a good warm correction and you set the clock after you boot, RighTime will serve well. To run RighTime in this mode, add (as the first TSR, but after any PROMPT, PATH or SET statements) the following line in the AUTOEXEC.BAT file: dev:\path\RighTime /N /Wwarm or dev:\path\RighTime /N /W You might want to follow this with a TIME command (perhaps preceded by a DATE command) to remind you to set the clock at each boot. Installation Error Messages RighTime might report one of the following messages at installation execution time: "DOS version 3.0 or later is required" The PC/AT "CMOS" hardware clock is not supported by earlier DOS versions. "System is not 80286 code compatible" RighTime expects that the system processor is at least an 80286. The 80C286, 80386(DX), 80386SX, and the 80486 are also code compatible with the 80286. Systems that use the 8088, 8086, 80188, and the NEC V-series processors will not run RighTime. "No AT hardware clock is present or clock is not running" Either a hardware clock or BIOS failure prevents use of the clock, or the clock chip is not installed in the system. "Hardware clock alarm is not functioning" RighTime has failed a self test. Try again in a minute or so. If this message persists, please notify the author. "Alarm is not supported by BIOS" The BIOS has reported an unsuccessful attempt to set the clock alarm feature. The BIOS is not compatible with RighTime. "Already installed" RighTime is currently resident and running in the system. "Correction storage switch is required" Either the disk file (/F), CMOS RAM (/R) or no storage (/N) option must be specified in the command line. "Invalid switch" An unrecognized option switch is present in the command line. "Invalid parameter" A value associated with an option is inappropriate. "Directory must hold original RIGHTIME.TXT during evaluation" The unregistered shareware distributed versions of RighTime and TestTime require that their directory contains the original unmodified documentation file, RIGHTIME.TXT. "Program has been altered" RIGHTIME.COM has been modified in some way. Immediately delete it from your disk and replace it with the distributed program. PC/AT and MSDOS Clock Esoteria 18.2 DOS historians say that the designers of the PC tried to do the DOS system programmers a favor by dividing an hour into 65536 parts, or about 18.20444444 ticks per second, making the most significant 16 bits of the 32 bit tick count directly indicate the hour and theoretically simplifying the system code. Somehow the hardware didn't turn out that way, resulting in about 176 extra ticks per day. The 8254 timer/counter clock input of 1193180 Hz and its counter 0 load constant of 0 (effectively 65536), yielded a hardware tick rate of approximately 18.20648193 ticks per second, and that remains so today. That looks like a small difference, but it amounted to an almost ten second gain per day. DOS designers corrected for the hardware error by redefining the number of ticks per day to include the extra ticks and a standard was set: the exact ticker rate was defined by the quotient of the number of ticks per day and the number of seconds per day (1573040/86400), which is approximately 18.20648148 ticks per second. When they did that, they made it possible to convert from ticks to time and from time to ticks in two ways, each way exact, but one according to the PC hardware implementation and one according to the day-length standard definition. Using only 16 bit integer arithmetic, the conversion that matches the PC hardware requires multiplying the current time in hundredthseconds by 59659 (which is 1193180/20), dividing that product by 65536 (discard the least significant 16 bits), then dividing that quotient by 5 to yield the tick count. The resulting rate is approximately 0.1820648193 ticks per hundredthsecond, which is the same as the hardware rate. The conversion for the day-length standard can be accomplished by multiplying the current time in hundredthseconds by 19663 (since 1573040/86400 = 19663/1080), dividing that product by 10800, then dividing that quotient by 10 to yield the tick count. The resulting rate is approximately 0.1820648148 ticks per hundredthsecond, the correct day-length standard rate. Ironically, MSDOS authors ignored their own day-length standard and chose to match the hardware to determine the time. The resulting error (compared to the day-length standard) is very small, only 0.039 tick per day, but for some requirements that can be significant. For example, if the resulting time is rounded or truncated to whole seconds, the two methods will yield different results for some values. For most applications though, the choice won't matter. Often, the number 18.2 or the period 55 milliseconds is used to describe the system clock (interrupts 8 and 1Ch) tick rate. In every case, that is not the correct number, but an approximation. Almost all PC "compatible" machines use this 18.2 standard tick rate, but there are exceptions; the AT&T 6300, for example, uses 18.75. Stability, Accuracy and Resolution Often confused, these three qualities are different and are only obliquely related, although each is required to exist in any good clock. They can be prioritized with little difficulty. Stability is foremost. Even if lacking in other qualities, a stable clock is useful if you know what to expect of it; an unstable clock generates worthless noise. Accuracy can only be meaningful if the clock is stable. Resolution is required only to meet the requirements of the clock's task; to catch a train on time, for example, you don't need hundredths of a second resolution, just an accurate, stable clock that will tell the time to minutes, or maybe only hours. Translation Gain, Resolution and Truncation Losses Suppose that some accurate clock resolves only to minutes, and you read the clock often at random, or asynchronous, times. Your time reading will be correct if it is made at the instant the minutes have incremented from one number to the next, but your reading will appear to be just under one minute low if made at the instant before the next minute increment. If you do this enough, the average or mean error of your readings will prove to be one half minute low. This is the mean resolution loss; an artifact of any finite resolution, resolution loss is present when asynchronously reading any accurate digital clock. Some applications require resolution loss compensation, which can be as simple as increasing the time by one-half of the unit of resolution of the clock; postcompensation can be applied when the time is read, or precompensation can be applied when it is set. In the example, the range of the compensated error would extend from 30 seconds low to 30 seconds high; the mean resolution loss would be zero. More sophisticated compensation schemes can synthetically increase the effective resolution of the clock, but resolution loss, though smaller, remains unavoidable. A similar effect, translation gain, occurs when asynchronously setting a digital clock; the instant of time set can occur anytime between one regular increment and the next. If set at the instant after an increment, no error results; if set immediately prior to an increment, however, the clock will be effectively set one unit too high. On the average, asynchronous clock sets will produce a clock time that is one-half unit of resolution high; negative precompensation of one-half unit of resolution will compensate for translation gain. Truncation loss is an effect that results from the disregard of digits of low significance. When converting from one time base to another, the result is often not an integral number in the new time base. If the fractional part is ignored, loss results. Arithmetic rounding to the nearest unit of resolution is effective compensation, and is easy to implement by adding one-half unit of resolution; the fractional part of the sum is then discarded by the time set function. In the PC/AT, all of these compensations are useful, and when combined, they are easy to implement. Translation and truncation errors are intrinsic to the function of RighTime and are compensated, and since few application programs - nor DOS itself - consider resolution loss, it is precompensated. TestTime Included with RighTime is a program tool that can provide some interesting insight into the relationship of the clocks in your system and the function of RighTime. TestTime takes no command line parameters. It will determine and express whether or not RighTime is running in the system, and it provides a continuous single line display of the clock system status. The status line is terse: H[date:hh:mm:ss(:aa)] D[date:hh:mm:ss] corr diff distrib where H is the hardware clock data. (:aa) is the alarm seconds data. While RighTime is running, the alarm seconds will increment in four second steps; D is the DOS system clock data; corr is the current correction that is applied to the DOS system clock in hundredthseconds, if RighTime is resident; diff is the signed time difference between the hardware and DOS clocks in seconds. A positive difference indicates that the DOS clock leads the hardware clock (it displays a higher, or later, time). Since DOS can only express time to 55 millisecond resolution in hundredthseconds, the difference is determined by a 100-sample averaging method whose accuracy improves with time. The last character of diff will initially be an approxima (a wavy equal sign) to indicate that full accuracy has not been achieved; it will change to an equal sign or a one-half sign when the difference is accurate. A one-half sign indicates that the difference value is between hundredths (an average of 5 milliseconds of resolution); distrib contains three numbers corresponding to the percentage of difference samples that are negative, zero, and positive. When the average difference is zero, the distribution of differences should ideally be balanced around zero. As the DOS clock drifts away from the hardware clock, the balance will shift until all samples are positive or negative. An arrow to the left of each seconds data indicates which data last changed. You can use TestTime to learn much about the behavior of the two clocks in your system. Try running it without RighTime installed and notice that the DOS clock is never the same as the hardware clock. Set the time and run TestTime again; if your DOS sets the hardware clock, check to see if the seconds are synchronized. They probably are not. Run TestTime some time later and see if the relationship between the clocks has changed; there's a good chance that it will have. Which, if either, is correct? Try these things with RighTime installed and see the difference for yourself. Briefly, How RighTime Works Every four seconds, RighTime reads the hardware clock time and calculates and sets the proper system time tick count. As usual, DOS continues to increment that count at each 55 millisecond timer tick interrupt and uses the count to determine the time whenever it is requested. When the user or an application program resets the time, RighTime determines the sign and magnitude of the adjustment and uses this data to modify correction factors that it maintains. RighTime normally stores these corrections in CMOS RAM or in its own program file on disk. Every two minutes, RighTime stores the current time so the period of inactivity can be determined when the system is next booted. The proper (cool) adjustment can then be calculated and the hardware clock can be adjusted if it is required. If the cool adjustment spans midnight, the date will be appropriately adjusted. RighTime provides a plus or minus 500 millisecond correction range. When the calculated system clock time and the hardware clock time differ by 500 milliseconds, RighTime advances or retards the hardware clock as needed to keep the correction within range. This adjustment is automatic and will not affect the DOS clock which remains correct at all times. RighTime takes interrupt 4Ah and hooks interrupts 8h, 1Ah, 21h, 28h and 2Fh, and it is TesSeRact compatible. Use of the features of the hardware clock is central to the function of RighTime, so the hardware clock is strongly guarded. While RighTime is installed, any attempt (via interrupt 1Ah) to set the hardware clock time, date or alarm time, or to disable the alarm, will be ignored and will produce an error indication to the offending program. If interrupt 4Ah is taken by another program, it will be recovered by RighTime. The program is resistant to modifications. Command Line Syntax RighTime [{/F|/R[addr]|/N}] [/W[[{+|-}]warm]] [/C[[{+|-}]cool]] [/Dmm] [/Umm] where /F causes RighTime to store corrections in its own program file; /R causes RighTime to store corrections in 13 CMOS RAM locations ending in addr (default 63, see /Raddr, below); /N disables correction storage; /W sets starting warm correction rate in hundredthseconds per day (default 0, maximum +32767 or -32768); /C sets starting cool correction rate, as above; /D changes the cool adjust period allowance (after boot) from the 10 minute default. The valid range is 1 to 60. Consider this option if your system exhibits a large difference in warm and cool corrections and cabinet temperature is suspect. You should also consider that the clock rate might be affected by the lower supply voltage when the system is off; /U changes the CMOS RAM or file update period from the two minute default. The valid range is 2 to 60, and the value should be even. If you think the default is unnecessarily frequent, try this option. Remember that this is part of the cool correction process, and less frequency might affect correction accuracy in severe situations; /Raddr will place the corrections in CMOS RAM at a location other than the default of 63; this location is that of the last of 13 bytes that are stored. This option is potentially harmful, since a careless value might allow RighTime to overwrite setup data; inadvertently changing a hard disk type, for example, can lead to a sad consequence. Be careful. Hardware Compatibility RighTime requires a hardware real time clock that is compatible with the stock PC/AT part, an MC146818. The Dallas Semiconductor DS1287 is one such part. Some modern PC/AT implementations provide an embedded hardware clock, not a separate part, that is fully compatible. The hardware clock and CMOS RAM usability depends upon the hardware and the BIOS: The Tandy 1000TL hardware is not compatible. An Award 286 BIOS in an unlabeled AT clone did not support the alarm feature of the hardware clock and is not compatible with RighTime. Toshiba laptops will not allow the use of CMOS RAM but no ill effects result from trying aside from a checksum error at the next boot which requires only a key press to correct. Use the disk file (/F) option. To date, all other AMI, DTK, Oak and Phoenix BIOS ROMs have worked well. If You Have Trouble Please note the symptoms and circumstances as thoroughly as is reasonably possible and contact Tom Becker Air System Technologies, Inc. 14232 Marsh Lane, Suite 339 Dallas, Texas 75234 USA Telephone: 214/402-9660 CompuServe: 76436,3210 RighTime Usage Registration Form Fill out this form, enclose the required funds and mail to: Air System Technologies, Inc. 14232 Marsh Lane, Suite 339 Dallas, Texas 75234 USA I would like to register the usage of RighTime. Name:________________________________________________________________ Business name:_______________________________________________________ Address:_____________________________________________________________ _____________________________________________________________ City:______________________________ State:_________ Zip:_____________ Telephone:_________________________ Where did you get RighTime?__________________________________________ Registered RighTime programs are serial numbered. Registration is required for each copy of RighTime that is simultaneously machine resident. If you have, for example, three machines on which you want to run RighTime, please register for three machines. Single machine registration fee is $25. Each additional machine registration fee is $15. How many copies of the RighTime package do you want?_________________ On what media? 5.25"/360K______ 3.25"/720K______ Total enclosed: US$____________ Make your check or money order payable to Air System Technologies. Does your business require an invoice?____________ Thank You!